graphql-ws

What is graphql-ws?

The graphql-ws package is a lightweight and fast WebSocket server and client for GraphQL subscriptions, designed to work with the GraphQL JavaScript reference implementation. It allows you to set up a full-duplex communication channel between the client and server to facilitate real-time data exchange using the GraphQL protocol.

What are graphql-ws's main functionalities?

Creating a WebSocket server for GraphQL subscriptions

This code sample demonstrates how to create a WebSocket server that handles GraphQL subscriptions. It uses the `useServer` function from `graphql-ws` to attach the WebSocket server to an existing HTTP server.

const { createServer } = require('http');
const { execute, subscribe } = require('graphql');
const { useServer } = require('graphql-ws/lib/use/ws');
const { schema } = require('./my-graphql-schema');

const server = createServer(function weServeSocketsOnly(_, res) {
  res.writeHead(404);
  res.end();
});

const wsServer = new WebSocket.Server({
  server,
  path: '/graphql',
});

useServer({ schema, execute, subscribe }, wsServer);

server.listen(4000);

Creating a WebSocket client for GraphQL subscriptions

This code sample shows how to create a WebSocket client that can subscribe to GraphQL subscriptions. The `createClient` function from `graphql-ws` is used to establish a connection to the WebSocket server, and the `subscribe` method is used to listen for real-time data updates.

const { createClient } = require('graphql-ws');

const client = createClient({
  url: 'ws://localhost:4000/graphql',
});

client.subscribe(
  {
    query: 'subscription { somethingChanged { id } }',
    variables: {},
  },
  {
    next: data => console.log('data received:', data),
    error: err => console.error('error during subscription:', err),
    complete: () => console.log('subscription completed'),
  }
);

Other packages similar to graphql-ws

subscriptions-transport-ws

This package is another implementation of GraphQL over WebSocket protocol. It is the predecessor of graphql-ws and was developed by the Apollo team. However, it is now deprecated in favor of graphql-ws, which is more lightweight and has a simpler API.

apollo-server

Apollo Server is a community-driven, open-source GraphQL server that works with many Node.js HTTP server frameworks. Apollo Server supports subscriptions with WebSocket and integrates well with the Apollo ecosystem. It is more feature-rich but also heavier compared to graphql-ws, which is focused solely on WebSocket communication.

README

Coherent, zero-dependency, lazy, simple, GraphQL over WebSocket Protocol compliant server and client.

Use Server-Sent Events (SSE) instead? Check out graphql-sse!

Get started

Swiftly start with the get started guide on the website.

Recipes

Short and concise code snippets for starting with common use-cases. Available on the website.

Documentation

Auto-generated by TypeDoc and then rendered on the website.

How does it work?

Read about the exact transport intricacies used by the library in the GraphQL over WebSocket Protocol document.

Want to help?

File a bug, contribute with code, or improve documentation? Read up on our guidelines for contributing and drive development with yarn test --watch away!

Disclaimer

This library and the GraphQL over WebSocket Protocol are not cross-compatible with the deprecated subscriptions-transport-ws and its accompanying Protocol.

You must use graphql-ws coherently and implement the GraphQL over WebSocket Protocol on both sides, server and the client.